The following is from an email sent by Dave Blasby which is the best guideline we have right now... The ideas were reviewed in the a recent geoserver IRC meeting, and some guidence has been provided buy Justin on documentation requirements.
Chris Holmes sent me the following summary:
- Main thing is build working quickly, and documentation.
And here is a link to daves email:
I will splice sections of dave's email into each section.
So lets see what we can figure out from this email? To start with it was
directed at the FM branch which involved a few of those questions about
the build system.
Many of the other points are still valid - lets go through them.
Guidelines and Ground Rules
Don't break the build!
I know that this is open source common sense, but some important issues were highlighted:
- build time matters
- ability to test, deploy etc matters.
In short if your changes slow us down they will be rolled back, unit tests must be fast or they are will not be run (and are thus broken).
- The build system is still a bit clunky. It takes me just under 10 minutes to do a build. Under the old system it would take at most 1.5 minutes - most of the time it would take less than 1/2 a minute.
- I need an easy way of being able to do a geotools build and have geoserver restart with the new jars. Under the old system I had a 3 line script that would (a) build geotools (b) copy the gt main jar to the geoserver lib/ directory (for future builds) and (c) copy the jar to the deployed server's lib/ directory. That way I could just stop geoserver, run my script, and then restart geoserver. I'd have the same configuration with the new jars up in less than a minute (most of that time spent building geotools). This makes doing geotools development (and testing) easy. I'm completely lost in the
new system.- I also need a way to build a new geoserver.jar and put it inside the deployed server. There is an ant task to do this (I think its called "move geoserver.jar") - its only 2 lines long. This allows me to quickly make changes to geoserver and run test them in the same configuration.
In fact, the only time I do a full geoserver build is when I modify the .jsp file or deploy a new configuration (and if I did the latter more often I'd have an ant task to just refresh the .jsps in the deployed server). 10 minutes is forever. If I do that 6 times, it means that I've wasted an entire hour. I hate being that unproductive.
Don't break the documentation!
This makes sense, if you change the code or design update the documentation to match. You cannot expect others to learn the system if the documentation does not match what is in svn.
- Update the Documentation
- If Others cannot work on it, it is not Done
This requirement is not to scary unless you are doing scary work. It is too bad that the 1.4.x branch is setting up a framework and thus actually needs to worry about this issues. For most projects this will be a non issue.
Here is how you can get that done:
- make your doc pages (for RnD work on branches) here in GEOSDEV
- the work will be included in the Developers Guide page when the work merges to trunk
- the pages will be moved to GEOSDOC when trunk is released as stable
Note if you need to modify existing pages on GEOSDOC you will need hack at a copy in GEOSDEV:
- Create a page with the same name in GEOSDEV
- Cut and paste the contents over to GEOSDEV
- attach any needed pictures
- We need to update ALL the documentation to account for this. There's no use in having "How does a GetFeature request work?"
documentation if you get lost in the 1st step. We also need new documentation so current developers can figure out whats going on - I know I'm lost.
If it isnt updated, then we have two other major problems:
- #* people who are new to geoserver will not take us at all seriously if documentation and reality are massivily out-of-alignment.
- by not updating existing documentation you are telling the saints who actually write it that their efforts are in vain. It hard enough to get people to write documentation, but impossible if you're going to obsolute it and not correct it.
To accomplish this we need to ensure that a Wiki is available where the docs can be updated as part of the merge process. We tried to get a "copy" of the GeoServer 1.3 documentation made as a starting point but were unsuccessful.
This cannot be expected of the community without improvements to the infrastructure.
We could update the docs on the web page as long as it clear that GEOSDOC is for trunk
While we could update the existing Home documentation directly this would impact users already using the stable branch (of course they could/should make use of the export of this documentation included in their release).
We need wiki space to create docs for 1.4.x without having to prepend 1.4.x to every page in order to not step on the toes of 1.3.x. GEOSDEV seems to be the place to do this.
I plan to import the relevant docs from GEOSDOC (architecture docs, articles new architecture, etc..), and the previous version of the 1.4.x developers guide which is being updated.
No one night stands (Maintence)
This is about commitment, and you thought commit access was enough. Seriously the maintence questions is a big one, we cannot
accept code that we cannot maintain (even if we like it).
- Don't Love us and Leave us
If we cannot maintain your code we cannot accept it, if you have a plan to keep it going that of course changes everything.
A middle ground can be had if you develope in a "Community Module", you can keep up with trunk and not impact the community.
- Are all the changes taking place on the current trunk in 1.4?
Who's moving changes between the stable branch and trunk? How about
moving bug fixes between 1.4 and the stable branch? - Who's doing maintance? Do they have actual time to do it?
Community and Communication
Dave mentioned checking with "the raster people", this is an example of "communication" to keep the geoserver community ticking along. Communication happens via email, and via some IRC meetings. Please ask, be aware, and develop your RnD work in a public manner so you can be sure that your changes do not negativly effect the happiness of others.
- Play nice
- I'd like to hear what the raster branch people think. Its probably going to take them a while to merge their old-and-modified-version to the new-and-modified-and-shuffled version.
Copyright and Wrong
We do need an IP check, at a minium TOPP uses the GPL license to protect itself, in addition TOPP also owns copyright and
needs to be sure that you have not stepped on any IP or patent toes.
- Copyright TOPP
- Able to be GPLed
- Free of IP or Patent troubles
While we start in good faith we will be forced to turf any changes that cannot meet these requirements.
Release Early Release Often
After you have done your merge, stick out a release. While this is overhead it does ensure that you have not broken anything
and allows the user community to provide you with feedback. Note a milestone release is often sufficient.
- I'd like to continue having a new stable release every 2-4 weeks. That means releases on the stable branch, not 1.4 releases. 1.4 can release on whatever schedule it wants - just make sure that we clearly differenciate between the two so people dont accidently download one..
- Release
If milestone releases happen too often (say once a week) we can go to a monthly schedule, or you can negotiate with another team and join up
to share the responsibility.
Quality and Assurances
This is a hard one, GeoServer needs to meet the following guidelines to "be geoserver".
- CITE tests (so we stay certified)
- Dont merge big changes onto trunk until they are actually very good.
